Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Opt.man < prev next >

Wrap

Text File | 1991-02-08 | 14.6 KB | 399 lines

Opt C Library Procedures Opt _________________________________________________________________ NNAAMMEE Opt_Parse, Opt_PrintUsage - Manage command line options SSYYNNOOPPSSIISS ##iinncclluuddee <<ooppttiioonn..hh>> int OOpptt__PPaarrssee(_a_r_g_c, _a_r_g_v, _o_p_t_i_o_n_A_r_r_a_y, _n_u_m_O_p_t_i_o_n_s, _f_l_a_g_s) void OOpptt__PPrriinnttUUssaaggee(_c_o_m_m_a_n_d_N_a_m_e, _o_p_t_i_o_n_A_r_r_a_y, _n_u_m_O_p_t_i_o_n_s) AARRGGUUMMEENNTTSS int _a_r_g_c (in) Number of arguments on command line. char **_a_r_g_v (in/out) Command line arguments passed to main program. char *_c_o_m_m_a_n_d_N_a_m_e (in) Name of the program being run, usually _a_r_g_v[0]. Option *_o_p_t_i_o_n_A_r_r_a_y (in) An array of option descriptions. int _n_u_m_O_p_t_i_o_n_s (in) Number of elements in optionArray, usually obtained using the OOpptt__NNuummbbeerr macro, e.g. OOpptt__NNuummbbeerr(optionArray). int _f_l_a_g_s (in) If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The only flags currently defined are OPT_ALLOW_CLUSTERING and OPT_OPTIONS_FIRST. _________________________________________________________________ DDEESSCCRRIIPPTTIIOONN OOpptt__PPaarrssee parses the command line arguments of a program according to an array of option descriptions. Starting with _a_r_g_v[1], it parses as many options as it can and returns the rest of the options in the _a_r_g_v array, compacted to the beginning of the array (starting with _a_r_g_v[1]). The return value indicates how many options are returned in the _a_r_g_v array (including _a_r_g_v[0]). Opt_Parse returns options that don't start with ``-'' unless they are arguments for options that it parses. OOpptt__PPaarrssee also returns any options follow- ing an OOPPTT__RREESSTT option (see below for more details). Sprite v.1.0 Printed: February 8, 1991 1 Opt C Library Procedures Opt Each element of the array _o_p_t_i_o_n_A_r_r_a_y has the following structure: ttyyppeeddeeff ssttrruucctt Option { iinntt _t_y_p_e; cchhaarr*_k_e_y; cchhaarr*_v_a_l_u_e_P_t_r; cchhaarr*_d_o_c_M_s_g; } Option; The _k_e_y field is a string that identifies this option. For example, if _k_e_y is ffoooo, then this Option will match a --ffoooo command-line option. If _k_e_y is the empty string (``'') then it matches a -- command-line option. If _k_e_y is NULL, the Option will not match any command-line options (this feature is only useful for OPT_DOC options). _D_o_c_M_s_g is a documenta- tion string to print out as part of a help message. The _t_y_p_e field determines what to do when this Option is matched. It also determines the meaning of the _v_a_l_u_e_P_t_r field. _T_y_p_e should always be specified using one of the following macros: OOPPTT__TTRRUUEE Treats _v_a_l_u_e_P_t_r as the address of an integer, and stores the value 1 in that integer. OOPPTT__FFAALLSSEE Treats _v_a_l_u_e_P_t_r as the address of an integer and stores the value 0 in that integer. OOPPTT__CCOONNSSTTAANNTT(_v_a_l_u_e) This is a generalized form of OPT_TRUE and OPT_FALSE. Treats _v_a_l_u_e_P_t_r as the address of an integer and stores _v_a_l_u_e in that integer. _V_a_l_u_e must be a positive integer. OOPPTT__IINNTT The next argument after the one matching _k_e_y must con- tain an integer string in the format accepted by ssttrrttooll (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). _V_a_l_u_e_P_t_r will be treated as the address of an integer, and the value given by the next argument will be stored there. OOPPTT__TTIIMMEE The next argument after the one matching _k_e_y must con- tain a string that is parsable as a date and time. Currently, only two formats are recognized: _s_e_c_o_n_d_s and Sprite v.1.0 Printed: February 8, 1991 2 Opt C Library Procedures Opt _y_y.._m_m.._d_d.._h_h.._m_m.._s_s The first form is simply the number of seconds since the start of the epoch (1 January 1970, 0 hours GMT). The second form specifies the year (e.g., 91 or 1991), month (1-12), day of the month, hours (0-23), minutes (0-59), and seconds (0-59). All fields must be speci- fied. _V_a_l_u_e_P_t_r will be treated as the address of a ttiimmee__tt (defined in <<ttiimmee..hh>>), and the given time will be stored there. All times are in terms of the current timezone and daylight savings rules. Note that this flavor can clobber the static buffer used by the llooccaallttiimmee library routine. OOPPTT__FFLLOOAATT The next argument after the one matching _k_e_y must con- tain a floating-point number in the format accepted by ssttrrttooll. _V_a_l_u_e_P_t_r will be treated as the address of an double-precision floating point value, and the value given by the next argument will be stored there. OOPPTT__SSTTRRIINNGG Treats _v_a_l_u_e_P_t_r as the address of a (char *), and stores a pointer to the next argument in the location pointed to by _v_a_l_u_e_P_t_r. OOPPTT__DDOOCC This option is intended primarily as a way of printing extra documentation during help message printouts. It isn't normally used as an actual option (and normally its _k_e_y field is NULL). If it is invoked as an option, then the same thing happens as for the ``-?'' option: descriptions get printed for all options in _o_p_t_i_o_n_A_r_r_a_y and OOpptt__PPaarrssee calls exit(0) to terminate the process. OOPPTT__RREESSTT This option is used by programs that allow the last several of their options to be the name and/or options for some other program. If an OOPPTT__RREESSTT option is found, then OOpptt__PPaarrssee doesn't process any of the remaining arguments; it returns them all at the begin- ning of _a_r_g_v. In addition, OOpptt__PPaarrssee treats _v_a_l_u_e_P_t_r as the address of an integer value, and stores in that value the index of the first of the OOPPTT__RREESSTT options in the returned _a_r_g_v. This allows the program to distin- guish the OOPPTT__RREESSTT options from other unprocessed options that preceeded the OOPPTT__RREESSTT. OOPPTT__FFUUNNCC When one of these options is encountered, _v_a_l_u_e_P_t_r is treated as the address of a function which is then Sprite v.1.0 Printed: February 8, 1991 3 Opt C Library Procedures Opt called with the following calling sequence: iinntt _f_u_n_c(_o_p_t_S_t_r_i_n_g, _n_e_x_t_A_r_g) cchhaarr *_o_p_t_S_t_r_i_n_g; cchhaarr *_n_e_x_t_A_r_g; { } The _o_p_t_S_t_r_i_n_g parameter points to the current option, and _n_e_x_t_A_r_g points to the next option from _a_r_g_v (or NULL if there aren't any more options in _a_r_g_v. If _f_u_n_c uses _n_e_x_t_A_r_g as an argument to the current option (so that Opt_Parse should skip it), then it should return 1. Otherwise it should return 0. OOPPTT__GGEENNFFUUNNCC Treat _v_a_l_u_e_P_t_r as the address of a function and pass all of the remaining arguments to it in the following way: iinntt _g_e_n_f_u_n_c(_o_p_t_S_t_r_i_n_g, _a_r_g_c, _a_r_g_v) cchhaarr *_o_p_t_S_t_r_i_n_g; iinntt _a_r_g_c; cchhaarr **_a_r_g_v; { } _A_r_g_c and _a_r_g_v refer to all of the options after the one that triggered the call, and _o_p_t_S_t_r_i_n_g points to the triggering option. _G_e_n_f_u_n_c should behave in a fashion similar to OOpptt__PPaarrssee: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of _a_r_g_v (starting at _a_r_g_v[0]). _G_e_n_f_u_n_c should return a count of how many arguments are left in _a_r_g_v; OOpptt__PPaarrssee will process them. FFLLAAGGSS OOPPTT__AALLLLOOWW__CCLLUUSSTTEERRIINNGG This will permit several options to be clustered together with a single ``-'', e.g., ``foo -abc'' will be handled the same way as ``foo -a -b -c''. OPT_ALLOW_CLUSTERING is likely to cause confusing behavior unless each option is identified with a single character. OOPPTT__OOPPTTIIOONNSS__FFIIRRSSTT This causes OOpptt__PPaarrssee to stop parsing the command line anytime something that is not an option is detected. Sprite v.1.0 Printed: February 8, 1991 4 Opt C Library Procedures Opt Thus, a program that takes some options followed by a command to execute (along with that command's options) can parse its own options using OPT_OPTIONS_FIRST. When the command to execute is encountered, assuming it does not begin with a hyphen, OOpptt__PPaarrssee will return the command and its arguments starting at _a_r_g_v[1], ignoring any arguments with hyphens following the first non- option. UUSSAAGGEE MMEESSSSAAGGEE OOpptt__PPrriinnttUUssaaggee may be invoked to print out all the documen- tation strings (plus option names and default values) for a command's options. If OOpptt__PPaarrssee encounters an option ``-?'' or ``-help'', then it will call OOpptt__PPrriinnttUUssaaggee and exit. Note: in some shells the question-mark must be escaped (e.g., ``foo -\?'' in _c_s_h). EEXXAAMMPPLLEE Here is an example definition of a set of option descrip- tions and some sample command lines that use the options. Note the effect on argc and argv; command arguments that get interpreted as options or option values are eliminated from argv, and argc is updated to reflect reduced number of arguments. /* * Define and set default values for globals. */ Boolean debugFlag = FALSE; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Option optionArray[] = { OPT_TRUE, "X", (char *) &debugFlag, "Turn on debugging printfs", OPT_INT, "N", (char *) &numReps, "Number of repetitions", OPT_STRING, "of", (char *) &fileName, "Output filename", OPT_REST, "x", (char *) &exec, "File to exec, followed by any arguments (must be last argument).", }; main(argc, argv) int argc; char *argv[]; { Opt_Parse(argc, argv, optionArray, Opt_Number(optionArray), OPT_ALLOW_CLUSTERING); Sprite v.1.0 Printed: February 8, 1991 5 Opt C Library Procedures Opt /* * the rest of the program. */ } Note that default values can be assigned to option vari- ables. Also, numOptions gets calculated by the compiler in this example. Here are some example command lines and their effects. prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps In all of the above examples, the return value from Opt_Parse will be 2, _a_r_g_v[0] will be ``prog'', _a_r_g_v[1] will be ``infile'', and _a_r_g_v[2] will be NULL. KKEEYYWWOORRDDSS arguments, command line, options Sprite v.1.0 Printed: February 8, 1991 6